/**
 * @IQueue.as
 * 
 * @author sodaChen mail:asframe#163.com
 * @version 1.0
 * <br>Copyright (C), 2012 ASFrame.com
 * <br>This program is protected by copyright laws.
 * <br>Program Name:ASFrame Collections
 * <br>Date:2012-1-19
 */
package com.asframe.collections.queues
{
	import com.asframe.collections.ICollection;
	
	/**
	 * A collection designed for holding elements prior to processing.
	 * Besides basic {@link java.util.Collection Collection} operations,
	 * queues provide additional insertion, extraction, and inspection
	 * operations.  Each of these methods exists in two forms: one throws
	 * an exception if the operation fails, the other returns a special
	 * value (either <tt>null</tt> or <tt>false</tt>, depending on the
	 * operation).  The latter form of the insert operation is designed
	 * specifically for use with capacity-restricted <tt>Queue</tt>
	 * implementations; in most implementations, insert operations cannot
	 * fail.
	 *
	 * <p>
	 * <table BORDER CELLPADDING=3 CELLSPACING=1>
	 *  <tr>
	 *    <td></td>
	 *    <td ALIGN=CENTER><em>Throws exception</em></td>
	 *    <td ALIGN=CENTER><em>Returns special value</em></td>
	 *  </tr>
	 *  <tr>
	 *    <td><b>Insert</b></td>
	 *    <td>{@link #add add(e)}</td>
	 *    <td>{@link #offer offer(e)}</td>
	 *  </tr>
	 *  <tr>
	 *    <td><b>Remove</b></td>
	 *    <td>{@link #remove remove()}</td>
	 *    <td>{@link #poll poll()}</td>
	 *  </tr>
	 *  <tr>
	 *    <td><b>Examine</b></td>
	 *    <td>{@link #element element()}</td>
	 *    <td>{@link #peek peek()}</td>
	 *  </tr>
	 * </table>
	 *
	 * <p>Queues typically, but do not necessarily, order elements in a
	 * FIFO (first-in-first-out) manner.  Among the exceptions are
	 * priority queues, which order elements according to a supplied
	 * comparator, or the elements' natural ordering, and LIFO queues (or
	 * stacks) which order the elements LIFO (last-in-first-out).
	 * Whatever the ordering used, the <em>head</em> of the queue is that
	 * element which would be removed by a call to {@link #remove() } or
	 * {@link #poll()}.  In a FIFO queue, all new elements are inserted at
	 * the <em> tail</em> of the queue. Other kinds of queues may use
	 * different placement rules.  Every <tt>Queue</tt> implementation
	 * must specify its ordering properties.
	 *
	 * <p>The {@link #offer offer} method inserts an element if possible,
	 * otherwise returning <tt>false</tt>.  This differs from the {@link
	 * java.util.Collection#add Collection.add} method, which can fail to
	 * add an element only by throwing an unchecked exception.  The
	 * <tt>offer</tt> method is designed for use when failure is a normal,
	 * rather than exceptional occurrence, for example, in fixed-capacity
	 * (or &quot;bounded&quot;) queues.
	 *
	 * <p>The {@link #remove()} and {@link #poll()} methods remove and
	 * return the head of the queue.
	 * Exactly which element is removed from the queue is a
	 * function of the queue's ordering policy, which differs from
	 * implementation to implementation. The <tt>remove()</tt> and
	 * <tt>poll()</tt> methods differ only in their behavior when the
	 * queue is empty: the <tt>remove()</tt> method throws an exception,
	 * while the <tt>poll()</tt> method returns <tt>null</tt>.
	 *
	 * <p>The {@link #element()} and {@link #peek()} methods return, but do
	 * not remove, the head of the queue.
	 *
	 * <p>The <tt>Queue</tt> interface does not define the <i>blocking queue
	 * methods</i>, which are common in concurrent programming.  These methods,
	 * which wait for elements to appear or for space to become available, are
	 * defined in the {@link java.util.concurrent.BlockingQueue} interface, which
	 * extends this interface.
	 *
	 * <p><tt>Queue</tt> implementations generally do not allow insertion
	 * of <tt>null</tt> elements, although some implementations, such as
	 * {@link LinkedList}, do not prohibit insertion of <tt>null</tt>.
	 * Even in the implementations that permit it, <tt>null</tt> should
	 * not be inserted into a <tt>Queue</tt>, as <tt>null</tt> is also
	 * used as a special return value by the <tt>poll</tt> method to
	 * indicate that the queue contains no elements.
	 *
	 * <p><tt>Queue</tt> implementations generally do not define
	 * element-based versions of methods <tt>equals</tt> and
	 * <tt>hashCode</tt> but instead inherit the identity based versions
	 * from class <tt>Object</tt>, because element-based equality is not
	 * always well-defined for queues with the same elements but different
	 * ordering properties.
	 *
	 *
	 * <p>This interface is a member of the
	 * Java Collections Framework</a>.
	 *
	 * @see java.util.Collection
	 * @see LinkedList
	 * @see PriorityQueue
	 * @see java.util.concurrent.LinkedBlockingQueue
	 * @see java.util.concurrent.BlockingQueue
	 * @see java.util.concurrent.ArrayBlockingQueue
	 * @see java.util.concurrent.LinkedBlockingQueue
	 * @see java.util.concurrent.PriorityBlockingQueue
	 * @since 1.5
	 * @author Doug Lea
	 * @param <E> the type of elements held in this collection
	 */
	public interface IQueue extends ICollection
	{
		/**
		 * Inserts the specified element into this queue if it is possible to do
		 * so immediately without violating capacity restrictions.
		 * When using a capacity-restricted queue, this method is generally
		 * preferable to {@link #add}, which can fail to insert an element only
		 * by throwing an exception.
		 *
		 * @param e the element to add
		 * @return <tt>true</tt> if the element was added to this queue, else
		 *         <tt>false</tt>
		 * @throws ClassCastException if the class of the specified element
		 *         prevents it from being added to this queue
		 * @throws NullPointerException if the specified element is null and
		 *         this queue does not permit null elements
		 * @throws IllegalArgumentException if some property of this element
		 *         prevents it from being added to this queue
		 */
		function offer(e:*):Boolean;
		
		/**
		 * Retrieves and removes the head of this queue,
		 * or returns <tt>null</tt> if this queue is empty.
		 *
		 * @return the head of this queue, or <tt>null</tt> if this queue is empty
		 */
		function poll():*;
		
		/**
		 * Retrieves, but does not remove, the head of this queue,
		 * or returns <tt>null</tt> if this queue is empty.
		 *
		 * @return the head of this queue, or <tt>null</tt> if this queue is empty
		 */
		function peek():*;
	}
}
